Please read the documents in this folder! They describe how to use high-level debuggers from Apple, Symantec, Metrowerks and Jasik Designs to debug an OpenDoc part handler. Read this document, then read the document for the particular debugger you are using.
This document also lists a number of common problems that can occur when loading or debugging a part, and tries to give solutions or hints.
OpenDoc setup.
This release includes (in the “Debugging Support” folder) a debugging version of OpenDoc, consisting of replacement libraries to copy in once you've installed the regular version. The debug build includes embedded symbols (MacsBug symbols on 68k, traceback tables on PPC) and lots of sanity checks that can help you debug your parts. See the “Debug Build” folder in the Developer Starter Kit.
We highly recommend using the debug build while working on your part editor, even though it's bigger, slower, and not officially supported. (We use it all the time ourselves.)
Important limitations.
• Remember that, as always, you can't debug drag-and-drop handlers (or anything called from them) using an application-based single-machine debugger such as the ones from Apple, Metrowerks or Symantec. You can use MacsBug, the two-machine serial-cable setup of the Apple debuggers, or Jasik's debugger. (The Metrowerks debugger tries to work around this in versions 1.2 and later. It succeeds part of the time. You can sometimes successfully hit a breakpoint (or a CPU exception) in the middle of a drag operation, but you may crash. Try it at your own risk.)
• System Object Model™ (SOM) objects are not inspectable, since their exact layout isn't known until runtime. There isn't currently any way to view the instance variables of a SOM object except by viewing the somThis local variable from inside a method of that object. The debugger and SOM teams at Apple are investigating ways to get around this problem.
Common problems.
There are various things that can go wrong that indicate various possible problems:
• “I get an error that says a ‘program error’ occurred. What error is this?”
Option-click the OK button for a second alert that gives the error number and possibly the name (in the debug build of OpenDoc) of the error code. Negative numbers in the -29000 range are OpenDoc errors, as listed in ErrorDef.idl.
• “When I open a document or stationery file, or drag it into an open document, I get a program error alert.”
We've beefed up error reporting and now the most common errors should have self-explanatory messages. If you get one that doesn't, find the error number, as described above.
— Common errors are in the range -2800...-2824, which are CFM errors indicating that the shared library couldn't be loaded, most likely due to unresolved imports or a malformed 'cfrg' resource. (Inside Mac: PowerPC System Software lists their meanings.)
— Other OpenDoc error codes, especially ones related to storage, in this situation might indicate that the document is damaged; throw it out and build a new stationery pad.
• “When I drop my part’s stationery into a document, I get a DebugStr warning that the library couldn't be loaded.”
This is OpenDoc warning you; you'll get this warning only when using the debug build of OpenDoc. The CFM error number appears in the message — most commonly it's -2804, which means the library couldn't be found. This usually indicates that the library names in your 'cfrg' and 'nmap' resources are not in sync with each other, your 'cfrg' version code doesn't match the one the linker put into your code, or your editor library couldn't be found in any Editors folder. You can also get -2807, which means there are missing imports (which are named in the error string.)
• “When I open a document or stationery file, I get a translation dialog instead of a document.”
This happens when OpenDoc cannot find an editor for the content of the root part of the document; it's a particular case of the next problem. Read on:
• “When I drop my part’s stationery into a document, I get a gray box instead of my content.”
This is the well-loved NoPart, which shows up when OpenDoc is unable to find a part editor to handle a given type of content. Its appearance in this context indicates a binding problem, probably in your 'nmap' resources.
— If this is your own part editor, double-check that the content types are correctly entered into the 'nmap's. If you're updating from DR3 to DR4, make sure you're using the official ISO string prefix for your types/kinds.
— Make sure the editor or an alias thereto is installed in an Editors folder.
— Make sure the editor is of the right flavor for the CPU you're running on (check the 'cfrg' resource.)
— Also try tossing out the stationery and regenerating new stationery by dropping your editor library onto the launcher.
— If that fails, also try tossing out the "OpenDoc Preferences" file from the OpenDoc Prefs folder of your Preferences folder.
• “When I launch my part editor or its stationery (or drop in on the OpenDoc launcher) nothing happens.”
This should not happen anymore; the launcher tries to catch any errors that prevent the document from launching and display an alert. If you get this problem, send us a bug report.
• “My library is loading and running (or crashing), but if I try to debug it I can never get the debugger to stop at any breakpoint I set.”
Sounds like the debugger is not targeting your library — it sees that the library has loaded, but it cannot find a matching sym file and so doesn't set up any breakpoints. This usually indicates a problem with file and library names: make sure you’ve followed the directions in the section “Part Editor Setup”, above.
• “When my editor is first loaded, I get a DebugStr warning about an incorrect heap magic number.”
If this happens the moment a part is instantiated — e.g. while creating stationery — it probably means you are using the ODMemory utility but not calling InitODMemory from your part's CFM init routine. Just add a call to that routine and that should fix it.
• “I get ‘MMWarning’s about invalid blocks or block headers.”
These come from the debug build of the OpenDoc memory manager; they mean either that someone is passing bad pointers to it (i.e. ones that don't point to blocks it allocated) or that the heap is corrupted. The warning should give the address of the block; you can use MacsBug to poke around near that address and compare the bytes there to the canonical block structure described in the “Memory Block Structure” document in the Technical Notes folder of the Developer Starter Kit. Also read the documents in the “Debug Build” folder.
• “I get an alert announcing a fatal SOM error, then the process quits.”
Option-click the "Quit" button for a second alert with more information in it, mostly produced by the SOM kernel itself. (In a non-debug build of OpenDoc this may provide little or no extra information.)
By far the most common SOM error is 20109, which you get by calling a method on a pointer that is not a valid SOM object — for instance, something like “foo->Baz(ev)” where foo is NULL, or garbage, or points to an already disposed object.
A special case of this is when the receiver is a real object but is not of the right class. For instance, if you take a pointer to an ODFrame, cast it to ODStorageUnit*, and then try to call a storage unit method on it, you may get a SOM error (or just a crash.) Using the CAST macro from ODDebug.h is a good way to detect this problem.
The second alert should give you information such as a pointer to the invalid object, and the name of the method that was called on it.
You might also get an error 20099, which indicates that SOM ran out of memory. This should only happen when instantiating objects in extreme low-memory situations. This is not friendly behavior for SOM; we're trying to see if we can eliminate this type of error!
The SOM Reference Manual includes a complete list of fatal errors, if you get one not described here.
